Revolution 1.1 external procedure call interface templates.

Revolution uses engine technology supplied by MetaCard Corporation.

These files have been produced by MetaCard Corporation.  However, please do 

not contact MetaCard corporation directly in the event of problems or questions, 

as with all issues relating to Revolution instead contact support@runrev.com.

  These files can be used to build executables with functions and

commands written in C that Revolution can call or vice versa.  See the

External Tutorial stack, "Externals Tutorial.rev" for more

information on writing XCMDS.  You may also find one of the HyperCard

books that cover externals useful.

  Externals can be written in languages other than C as long as they

pass data using C data structures, but no APIs are available for other

languages in this release.  The current API is compatible with the API

supported by Apple's HyperCard 1.2.  Future enhancements could support

more of the direct access to internal structures supported by the

HyperCard 2.0 API.

If you have any trouble building the externals, or need access to

specific data structures in Revolution please email to

support@runrev.com and let us know what you need.

=================== Building on UNIX systems =======================

There are three targets in the Makefile for UNIX systems:

  external contains example external commands and functions.  These

  are called by button scripts in the "External Tutorial" stack in the

  standard distribution.  To use it, build the executable and put it

  in the same directory as the Revolution engine or in the current

  directory.  When the "External Tutorial.rev" file is opened, Revolution

  forks and execs this file.  Pressing the buttons in the stack call

  the various functions.

  To build one or more of these targets on a UNIX platform, you should

uncomment the lines appropriate for your platform and then run "make".

Note that due to the wide variety of incompatibilities between the

various Unix systems, the variations in the strictness of different

vendors' compilers, and the many incompatibilities introduced by the

vendors themselves between versions of a given OS, no guarantee is

made that these files will compile without errors on your system.  It

may be necessary to change compiler command line options, or to add or

remove files included into the various .c source files.

  The current implementation of the external procedure call mechanism

on UNIX platforms uses X properties for communication between the

engine and the external process.  Due to the double client-server

round trip involved, it is probably not suitable for functions called

repeatedly in loops.  Use of an embedded engine will speed

calls to external C code by approximatedly a factor of 40 and so

should be used instead of the standard external mechanisms where

performance is a concern.  This is an extra cost, UNIX platform only product, 

contact us for details.

=================== Building on Windows systems =======================

  On Windows 95 and NT, externals are compiled into DLLs which are

loaded when the stack that uses the external is opened.  To build the

external for the "External Tutorials" stack you'll need to compile

external.c and XCmdGlue.c and link them together into a DLL named

external.dll.  With Visual C++, you do this by creating a new project

and importing those two files and the external.def into it, and then

building that project.

==================== Building on MacOS systems ========================

  On MacOS systems, the external is compiled into a CODE resource

which must be put in the resource fork of a stack file.  This of

course means that the external is attached to the main stack in that

file rather than to a substack as is the case on the other two

platform types.  To use the external tutorial, you must first create

an empty resource fork for the file "Externals Tutorial.rev" using Resedit.  The use

the CodeWarrior project to build the external and place it into the

"Externals Tutorials.rev" file when it prompts you for the destination.  Then start

up Revolution and open the external tutorial.